Basic operations on a scene

Open a scene

Use the loaddocument function:

-- load a sample
loaddocument ("$(SAMPLES)/Surface.gproject")

Save a scene

Use the savedocument function:

-- Save the current scene
savedocument ()

-- Or save to a different location
savedocument ("/tmp/scene.gproject")

Close a scene and restart with a fresh new document

Use the newdocument function:

-- Clean up everything
-- Make sure the user really wants it!
local warnIfCurrentModified = true
if not newdocument (warnIfCurrentModified) then
    print ("User aborted!")
end

Open and close a modification context

To modify a scene data (create new nodes, change plug value...) you must open a modification context. This allows Guerilla to track all the modifications as a single undo/redo action.

Use the Document:modify () method to declare a new modification context:

-- Create a new modification context
local mod = Document:modify ()
-- Change the timeline last frame
mod.set (Document.LastFrame, 100)
-- Close the modification context
mod.finish ()

The modifier is an object that can handle all the possible document modifications.

Create a new node

Use the Modifier.createnode function:

local mod = Document:modify ()
-- Create the 'Group' node at the root
mod.createnode (Document, "SceneGraphNode", "Group")
-- Don't forget to finish the modification!
mod.finish ()

Load a node from a file

Use the Node:loadfile () method:

-- Even though we don't explicitely use the modifier here
-- we still have to open a new modification context
local mod = Document:modify ()
-- Load the library cube primitive
local result = Document:loadfile ("$(LIBRARY)/primitives/cube.glocator")
if result then
    -- #result is the number of loaded nodes
    print ("We just loaded "..(#result).. " nodes:")
    for k, node in ipairs (result) do
        print (node:getname ())
    end
else
    print ("An error occured!")
end
-- Don't forget to finish the modification!
mod.finish ()

Save a node to a file

Use the Node:savefile () method:

-- No need for a modification context
local rg = _"RenderGraph"
if rg then
    rg:savefile ("/tmp/rg.grendergraph")
else
    print ("RenderGraph doesn't exist!")
end